Skip to content

Add single-user database recovery gate - #162

Merged
eamirian merged 1 commit into
mainfrom
codex/v1-recovery-gate
Aug 13, 2026
Merged

Add single-user database recovery gate#162
eamirian merged 1 commit into
mainfrom
codex/v1-recovery-gate

Conversation

@eamirian

Copy link
Copy Markdown
Contributor

What changed

  • adds domain-neutral, record-complete ACE database backup and clean-target restore services
  • adds bounded python -m core.engine.cli.commands.recovery backup|restore commands
  • emits a checksum manifest with ACE version, Surreal CLI version, schema head, namespace/database, size, inclusions, and explicit exclusions
  • proves a persisted Connect → Map → Watch → Brief Builder chain survives a real SurrealKV restart, a later append-only update, backup, and restore with a byte-identical resource page
  • fixes real-store Builder reopen behavior for JSON-compatible strict contracts and explicitly selects the immutable-record scope index
  • documents the operational recovery boundary and evidence

Why

ACE v1 needs an honest single-user recovery promise. A persisted Intelligence Builder must reopen after process/database restart, accept later append-only work, and be recoverable into a clean store without conflating runnable recovery with data portability.

A raw generated SurrealDB full-schema export is not replayable for the current ACE schema: historical migrations leave valid runtime indexes that refer to retired org fields, and clean import rejects those definitions. This implementation keeps SurrealDB's native serialization for all table records while rebuilding the exact packaged schema version before import.

Operator impact and boundaries

  • pause ACE ingestion and other writers while backup runs
  • restore refuses a target that already has database definitions
  • checksum, byte count, manifest contract, and schema version fail closed
  • failed imports leave a partial target that must be discarded
  • database users/access definitions, environment configuration, connector/provider credentials, external secret stores, and non-persisted source bodies are explicitly excluded
  • this is runnable ACE database record-state recovery, not product data portability
  • top-level ace recovery registration is intentionally excluded because PR Package and launch Atrium #156 owns core/engine/cli/main.py; the packaged module command is supported now and registration can be added after convergence

Verification

  • restacked onto Core main at 0948db68af3f3915132baed35b40549e305a35ea
  • real disposable SurrealKV restart/reopen + append + backup/clean restore + byte-identical resource page: 1 passed in 77.02s
  • focused recovery plus public/kernel boundary gate: 82 passed, 2 skipped
  • built ace_core-0.8.2 wheel contains both recovery modules; extracted-wheel help exposes bounded backup/restore commands
  • Ruff format/check and git diff --check: passed

Broad-gate limitations

The pre-restack broad non-E2E run reached 7897 passed, 50 skipped, 262 deselected and reported two failures:

  • forget-by-hash was a transient Surreal transaction conflict/stale shared state and passed isolated rerun.
  • governed-action child-process import still fails because the existing baseline test assumes a normal checkout; reproduced unchanged from a pristine archive of exact base 7142804e2e3479c8fdbbd062614803300fb7fb4e. This is the previously documented linked-worktree limitation, unrelated to recovery.

No UI, World, Market, collaboration, release, tag, publication, or top-level CLI-registration change is included.

@eamirian
eamirian marked this pull request as ready for review August 13, 2026 23:33
@eamirian
eamirian merged commit 8424b12 into main Aug 13, 2026
6 checks passed
@eamirian
eamirian deleted the codex/v1-recovery-gate branch August 13, 2026 23:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant